RULE #1: APPLESOFT PROGRAMS ONLY

The BC only works with unprotected 
ProDOS-based Applesoft BASIC programs.  You must have a copy of the program you want compiled saved on a ProDOS disk.
When you catalog a disk (by typing CAT),"BAS" identifies a file as being Apples-oft BASIC:

/SAMPLE.DISK

NAME        TYPE
----        ----
FILE.A      BAS (You can't compile basic                 programs)
FILE.B      BIN (you can't compile bina-                 ry files)
FILE.C      TXT (you can't compile text                  files)
FILE.D      SYS (forget it)
FILE.E.     VAR (ditto)
FILE.F      COM (here is a program that                  has been saved in comp-                 iled format)

*COM will read as
________________________________________

RULE #2: WATCH OUT FOR CERTAIN THINGS

o ProDOS' CHAIN, STORE & RESTORE comman-  ds make programs required special tre-  atment (See CHAIN, STORE & RESTORE CO-  MMANDS)

o Amperstand (&) statements with parame-  ters and the routines that they call    must be altered by someone with assem-  bly language experience (See HOW TO     WRITE AMPERSTAND ROUTINES)

o Some Applesoft commands are not compa-  tible - specifically CONT, DEL, LIST,   LOAD, NOTRACE, RECALL, SAVE, SHLOAD,    TRACE AND STORE (ProDOS' LOAD, STORE &  SAVE will compile)

o Weird memory pokes are unpredictable.   If the program you want to compile      pokes values into Zero Page or BASIC.   SYSTEM or some other exotic place, go   ahead and try compiling - if you're     lucky, you'll have no problems at all.
o Giant Applesoft programs are usually    compatible if you compile them to disk  without the COMPILER.SYSTEM file in     memory. To prevent COMPILER.SYSTEM      from loading into memory, boot a        normal ProDOS disk that loads BASIC.    SYSTEM, then insert the BC disk and     type the command BRUN COMPILER. Do      this only once because each time you    do it again it costs you 6k of memory.

_______________________________________


HOW TO RUN AN APPLESOFT PROGRAM AT      COMPILED SPEED:                         ----------------------------------

This is easy. First, be sure the        Compiler is installed in memory. Now    just run your program like you always doby typing:

RUN NAME or -NAME

After a brief "COMPILING..." message,   your program should be running at       machine language speed. Since compiled  programs have no line #'s, the ProDOS   command RUN NAME,@123 will not work (123represents any program line #).

_______________________________________



HOW TO SAVE A PROGRAM ON DISK IN        COMPILED FORMAT: 
--------------------------------

To save a compiled version of an Apples-oft program on the current disk, type:

COMPILE NAME, NEWNAME

Your Applesoft program will be loaded,  compiled and then saved on disk. A FILE TYPE MISMATCH error message here might  mean that you used the same name for    both files. You may use the same name   for the compiled file if you are saving onto another disk or directory. For exa-mple you could type:

COMPILE /DISK1/NAME,/DISK2/NAME

This command would load NAME from DISK1 and save it as NAME on DISK2 in compiledformat


_______________________________________


HOW TO MAKE A CHANGE TO A COMPILED      PROGRAM:
----------------------------------

You can't change a compiled program.    Instead, change the Applesoft "source"  program (the one you compiled in the 1stplace)

________________________________________

HOW TO MAKE CONTROL-C STOP A COMPILED   PROGRAM:
-------------------------------------

Normally Control-C will stop an Appleso-ft program but have no effect on compil-ed programs (except in response to INPUTstatements). To make Control-C halt a   compiled program, add a RESUME statementsomewhere in the program you are going  to compile. Think twice before using    this method, because it will have the   side effect of making your compiled pro-gram run somewhat slower. The RESUME st-atement has an undesirable effect on Ap-plesoft programs, so you should put it  somewhere where it can't possibly get   executed - like after the end of your   program (END:RESUME).

___For you Advanced Programmers:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

HOW TO SPECIFY A NEW ADDRESS FOR A      PROGRAM:
----------------------------------

Compiled programs normally load and run at address 2049 ($0801), just like Appl-esoft programs. You may run a compiled  program at a different address by chang-ing the Applesoft program before it is  compiled. For example, insert the follo-wing line at the beginning of TESTPROGR-AM to run it above hi-res 1 at 16384    ($4000):
1 IF PEEK(104)<>64 THEN POKE 16384,0:   POKE 104,64: PRINT CHR$(4)"RUN TESTPROG-RAM"

Replace the 64's with 96's and the      16384 with 24576 to load the program    above hi-res page 2 at 24576 ($6000).

You may also specify the address with a RUN command followed by a comma and the address. The following command will com-pile and run an Applesoft program-or a  compiled program-above page 1 and page 2respectively:

RUN NAME,A$4000
RUN NAME,A$6000

(Note: In this procedure, "RUN" cannot  be replaced with a hyphen.)

________________________________________

HOW TO WRITE PROGRAMS FOR MAXIMUM       COMPILED SPEED:
---------------------------------

The one major point to keep in mind to  make compiled programs run faster is    avoid using floating point values when- ever possible. The Compiler does all of its math using integer values whenever  it can - integers process faster
----------------------

o when a value 67 or   less than -32767

o when division is used in an expression
o when any of the following functions     are used ATN, COS, EXP, LOG, RND, SIN,  SQR OR TAN

Basic techni 
The following programming methods DO    speed up Applesoft programs but DO NOT  speed up compiled programs (they also   don't do any harm).

o Using real variables instead of         integer variables (Using A%=3 instead   of A=3 will not affect a compiled pro-  gram's speed)

o Using variables instead of numeric      constants (In a compiled program, A=PI  executes no faster than A=3.14159)

o Putting frequently-executed lines and   subroutines near the beginning of a     program.

o Putting frequently used variables near  the beginning of a program.


________________________________________

HOW TO USE PROGRAMS THAT USE THE CHAIN  COMMAND:
--------------------------------------

The ProDOS CHAIN command works just likethe ProDOS RUN command, but existing    variables stay intact. Programs that useCHAIN share common variables and must begiven special treatment for compiling tobe successful. Otherwise a FILE TYPE    MISMATCH error will occur. All programs involved with a CHAIN command to compileone program and a special COMMON commandto compile the other program(s). COMMON's syntax is similar to compile:

COMMON NAME,NEWNAME

COMMON must be used immediately after   COMPILE.


________________________________________


HOW TO COMPILE PROGRAMS THAT USE STORE  AND RESTORE COMMANDS:
--------------------------------------
(Note this section applies to the ProDOSSTORE and RESTORE commands. The Appleso-ft RESTORE command will compile just    fine, however the Applesoft STORE comma-nd is obsolete.)


The ProDOS STORE command normally saves the variables in memory on disk in a VARfile. RESTORE loads these variables backinto memory. Programs that use STORE andRESTORE share common variables and must be given special treatment for compilingto be successful. The programs must be  compiled on disk using the COMPILE comm-and on one program and the COMMON comma-nd on the other (see CHAIN). STORE & RE-STORE in compiled programs create and   use variable files of type CVR instead  of VAR.


________________________________________


HOW TO WRITE AMPERSAND ROUTINES FOR     COMPILED PROGRAMS:
-----------------------------------

An ampersand routine without parameters (& by itself) will compile just fine.   Ampersand routines with parameters (like&XXX or &XXX,YYY,ZZZ) are a different   story. Both the Ampersand command and   the machine language routine itself Use && instead of &

When calling an ampersand routine from acompiled program, you must use two cons-ecutive ampersands (for example, you    would use &&SORT instead of &&SORT).    This is how the Compiler detects progra-ms that have or have not been modified.

Change #2: Re-evaluate your parameters

With the Compiler installed, a JSR to   $98FD will evaluate the next parameter  after an ampersand:

o If the parameter is a string, a point-  er to the string will be found at       $F6,$F7. All strings in a compiled      program are stored with the length in   the first byte.

o If the parameter is a numeric value     and the carry flag is clear, the value  is an integer with its low byte in the  X-register and the high byte in the     Accumulator.

o If the parameter is a numeric value     and the carry flag is set, the value    is floating point and stored in FAC     (at $9D).

There is no way for the Compiler to det-ermine if the correct parameters are be-ing passed to your ampersand routines.  If the correct parameters are not there,the program will most likely crash mise-rably.


________________________________________

More info can be found on BC in the     following text files, ABOUT BEAGLE      COMPILER, BC APPLESOFT/PRODOS COMMAND   SUMMARY, BC ERRORS.

This documentation was typed by:
(*-Practor Fime-*)
Please excuse typos because these dox   were a rush job.

Call these fine systems:

Mother Board West.........(415) 994-2758The Haven.................(416) 485-7805Black Forest..............(617) 263-9413Dark Cosmos Elite.........(213) 476-7678The Courtroom Elite.......(213) 644-2760Smash*Palace*South........(512) 441-0095